---
type: integration
title: '@astrojs/cloudflare'
description: '@astrojs/cloudflare 어댑터를 사용하여 Astro 프로젝트를 배포하는 방법을 알아보세요.'
sidebar:
  label: Cloudflare
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/cloudflare/'
category: adapter
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro';
import ReadMore from '~/components/ReadMore.astro';
import Since from '~/components/Since.astro';
import { Tabs, TabItem, Steps } from '@astrojs/starlight/components';

이 어댑터를 사용하면 Astro가 [서버 아일랜드](/ko/guides/server-islands/), [액션](/ko/guides/actions/), [세션](/ko/guides/sessions/)을 포함하여 [요청 시 렌더링되는 라우트 및 기능](/ko/guides/on-demand-rendering/)을 [Cloudflare](https://www.cloudflare.com/)에 배포할 수 있습니다.

Astro를 정적 사이트 빌더로 사용하는 경우 어댑터가 필요하지 않습니다.

[Cloudflare 배포 가이드](/ko/guides/deploy/cloudflare/)에서 Astro 사이트를 배포하는 방법을 알아보세요.

## 왜 Astro Cloudflare인가?

Cloudflare [개발자 플랫폼](https://developers.cloudflare.com/)을 사용하면 스토리지 및 AI와 같은 리소스에 접근하여 풀스택 애플리케이션을 개발하고, 이 모든 것을 글로벌 에지 네트워크에 배포할 수 있습니다. 이 어댑터는 Cloudflare를 통해 배포할 수 있도록 Astro 프로젝트를 빌드합니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

Astro 프로젝트의 서버 렌더링을 활성화하려면 `astro add` 명령을 사용하여 Cloudflare 어댑터를 추가하세요. 그러면 `@astrojs/cloudflare`가 설치되고 `astro.config.mjs` 파일이 한 번에 적절하게 변경됩니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add cloudflare
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add cloudflare
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add cloudflare
  ```
  </Fragment>
</PackageManagerTabs>

이제 [페이지별로 요청 시 렌더링](/ko/guides/on-demand-rendering/#요청-시-렌더링-활성화)을 활성화하거나, [기본적으로 모든 페이지를 서버 렌더링](/ko/guides/on-demand-rendering/#server-모드)하도록 빌드 출력 구성을 `output: 'server'`로 설정할 수 있습니다.

### 수동 설치

<Steps>

1. 선호하는 패키지 관리자를 사용하여 `@astrojs/cloudflare` 어댑터를 프로젝트 종속성에 추가하세요.

    <PackageManagerTabs>
      <Fragment slot="npm">
      ```sh
      npm install @astrojs/cloudflare
      ```
      </Fragment>
      <Fragment slot="pnpm">
      ```sh
      pnpm add @astrojs/cloudflare
      ```
      </Fragment>
      <Fragment slot="yarn">
      ```sh
      yarn add @astrojs/cloudflare
      ```
      </Fragment>
    </PackageManagerTabs>

2. `astro.config.mjs` 파일에 어댑터를 추가합니다.

    ```js title="astro.config.mjs" ins={2,5}
    import { defineConfig } from 'astro/config';
    import cloudflare from '@astrojs/cloudflare';

    export default defineConfig({
      adapter: cloudflare(),
    });
    ```

3. [Wrangler 구성 파일](https://developers.cloudflare.com/workers/wrangler/configuration/)을 생성합니다.

    ```jsonc title="wrangler.jsonc"
    {
      "main": "dist/_worker.js/index.js",
      "name": "my-astro-app",
      // 배포하는 날짜로 업데이트합니다.
      "compatibility_date": "2025-03-25",
      "compatibility_flags": [
        "nodejs_compat",
        "global_fetch_strictly_public"
      ],
      "assets": {
        "binding": "ASSETS",
        "directory": "./dist"
      },
      "observability": {
        "enabled": true
      }
    }
    ```

4. `public/` 폴더에 `.assetsignore` 파일을 만들고 다음 줄을 추가합니다.

      ```txt title="public/.assetsignore"
      _worker.js
      _routes.json
      ```

</Steps>

## 옵션

Cloudflare 어댑터는 다음 옵션을 허용합니다.

### `cloudflareModules`

<p>
**타입:** `boolean`<br />
**기본값:** `true`
</p>

[`.wasm`, `.bin`, `.txt` 모듈의 가져오기](#cloudflare-모듈-가져오기)를 활성화합니다.

이 기능은 기본적으로 활성화되어 있습니다. 비활성화하려면 `cloudflareModules`를 `false`로 설정하세요.

### `imageService`

<p>
**타입:** `'passthrough' | 'cloudflare' | 'compile' | 'custom'`<br />
**기본값:** `'compile'`
</p>

어댑터에서 사용되는 이미지 서비스를 결정합니다. 호환되지 않는 이미지 서비스가 구성되면 어댑터는 기본적으로 `compile` 모드로 설정됩니다. 그렇지 않으면 전역적으로 구성된 이미지 서비스를 사용합니다.

* **`cloudflare`:** [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) 서비스를 사용합니다.
* **`passthrough`:** 기존 [`noop`](/ko/guides/images/#무작동-패스스루-서비스-구성) 서비스를 사용합니다.
* **`compile`:** Astro의 기본 서비스 (sharp)를 사용하지만 빌드 시 사전 렌더링된 경로에서만 사용됩니다. 요청 시 렌더링되는 페이지의 경우 모든 `astro:assets` 기능이 비활성화됩니다.
* **`custom`:** 항상 [이미지 옵션](/ko/reference/configuration-reference/#이미지-옵션)에 구성된 이미지 서비스를 사용합니다. **이 옵션은 구성된 이미지 서비스가 Cloudflare의 `workerd` 런타임에서 작동하는지 확인하지 않습니다.**


```js title="astro.config.mjs" ins={6}
import { defineConfig } from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({
     imageService: 'cloudflare'
  }),
})
```

### `platformProxy`

Cloudflare 런타임이 `astro dev`에 추가되는지 여부와 방법을 결정합니다. 여기에는 로컬 `workerd` 바인딩에 대한 프록시와 Cloudflare 특정 값의 에뮬레이션이 포함되어 있어 Node.js 개발 프로세스에서 런타임을 에뮬레이션할 수 있습니다. [Cloudflare 런타임](#cloudflare-런타임)에 대해 자세히 알아보세요.

:::note
제공되는 프록시는 최선을 다해 실제 프로덕션을 에뮬레이션한 것입니다. 최대한 실제와 비슷하게 설계되었으나 약간의 차이와 불일치가 있을 수 있습니다.
:::

#### `platformProxy.enabled`
<p>
**타입:** `boolean`<br />
**기본값:** `true`
</p>

개발 모드에서 Cloudflare 런타임을 활성화할지 여부를 결정합니다.

#### `platformProxy.configPath`
<p>
**타입:** `string`<br />
**기본값:** `undefined`
</p>

Wrangler 구성 파일의 경로를 정의합니다. 값을 설정하지 않으면 프로젝트 루트에 존재하는 `wrangler.toml`, `wrangler.json` 및 `wrangler.jsonc`를 추적합니다.

#### `platformProxy.environment`
<p>
**타입:** `string`<br />
**기본값:** `undefined`
</p>

사용할 [Cloudflare 환경](https://developers.cloudflare.com/workers/wrangler/environments/)을 설정합니다. Wrangler 구성 파일에 정의된 환경을 선택해야 하며, 그렇지 않으면 오류가 발생합니다.

#### `platformProxy.persist`
<p>
**타입:** `boolean | { path: string }`<br />
**기본값:** `true`
</p>

바인딩 데이터를 파일 시스템에 로컬로 저장할지 여부와 저장 위치를 설정합니다.

- `true`로 설정하면 바인딩 데이터는 `.wrangler/state/v3/`에 저장됩니다. 이는 wrangler의 기본 설정과 동일합니다.
- `false`로 설정하면 바인딩 데이터가 파일 시스템에 저장되지 않습니다.
- `{ path: string }`으로 설정하면 바인딩 데이터가 지정된 경로에 저장됩니다.

:::note
`wrangler`의 `--persist-to` 옵션은 내부적으로 `v3`라는 하위 디렉터리를 추가하지만 `@astrojs/cloudflare` `persist` 속성은 그렇지 않습니다. 예를 들어 `wrangler dev --persist-to ./my-directory`를 실행하는 것과 동일한 위치를 재사용하려면 `persist: { path: "./my-directory/v3" }`을 지정해야 합니다.
:::

다음 구성은 개발 서버를 실행할 때 Cloudflare 런타임을 활성화하고 `wrangler.json` 구성 파일을 사용하는 예시를 보여줍니다. 또한 파일 시스템에 데이터를 유지하기 위한 사용자 정의 위치를 지정합니다.

```js
import cloudflare from '@astrojs/cloudflare';
import { defineConfig } from 'astro/config';

export default defineConfig({
	adapter: cloudflare({
		platformProxy: {
			enabled: true,
			configPath: 'wrangler.json',
			persist: {
				path: './.cache/wrangler/v3'
			},
		},
	}),
});
```
### `routes.extend`

Cloudflare Workers에서는 이 옵션을 사용할 수 없습니다. 자세한 내용은 [Cloudflare Workers에서의 라우팅](#cloudflare-workers의-라우팅)을 참조하세요.

Cloudflare Pages에서 이 옵션을 사용하면 요청 시 생성되는 경로를 결정하기 위해 생성된 `_routes.json` 파일에 사용자 지정 패턴 (예: `/fonts/*`)을 추가하거나 제외할 수 있습니다. 이는 자동으로 생성할 수 없는 경로 패턴을 추가해야 하거나 사전 렌더링된 경로를 제외해야 하는 경우 유용할 수 있습니다.

사용자 지정 경로 패턴에 대한 자세한 내용은 [Cloudflare의 라우팅 문서](https://developers.cloudflare.com/pages/functions/routing/#functions-invocation-routes)에서 확인할 수 있습니다. 지정된 경로는 자동으로 중복 제거되지 않으며 기존 경로에 그대로 추가됩니다.

#### `routes.extend.include`

<p>
**타입:** `{ pattern: string }[]`<br />
**기본값:** `undefined`
</p>

Cloudflare 어댑터가 요청 시 생성할 추가 경로를 `routes.extend.include` 배열에 구성합니다.

#### routes.extend.exclude

<p>
**타입:** `{ pattern: string }[]`<br />
**기본값:** `undefined`
</p>

요청 시 렌더링에서 제외할 경로를 `routes.extend.exclude` 배열에 구성합니다. 대신 이러한 경로는 사전 렌더링되어 정적으로 제공되며 서버 함수를 호출하지 않습니다. 또한 이 옵션을 사용하면 서버 함수를 통해 요청을 라우팅하지 않고도 정적 자산 (예: 이미지, 글꼴, CSS, js, html, txt, json 등) 파일을 직접 제공할 수 있습니다.

```js title="astro.config.mjs"
export default defineConfig({
  adapter: cloudflare({
    routes: {
      extend: {
        include: [{ pattern: '/static' }], // 요청 시 렌더링을 위해 사전 렌더링된 페이지를 서버 함수로 라우팅합니다.
        exclude: [{ pattern: '/pagefind/*' }], // 빌드 시 정적으로 생성되는 Starlight의 pagefind 검색을 사용합니다.
      }
    },
  }),
});
```

### `sessionKVBindingName`
<p>
**타입:** `string`<br />
**기본값:** `SESSION`
<Since v="5.6.0" />
</p>

`sessionKVBindingName` 옵션을 사용하면 세션 스토리지에 사용되는 KV 바인딩의 이름을 지정할 수 있습니다. 기본적으로 `SESSION`으로 설정되어 있지만, 사용자 정의 KV 바인딩 이름과 일치하도록 변경할 수 있습니다. 자세한 내용은 [세션](#세션)을 참조하세요.

```js title="astro.config.mjs" "MY_SESSION_BINDING"
export default defineConfig({
  adapter: cloudflare({
    sessionKVBindingName: 'MY_SESSION_BINDING',
  }),
});
```

### `workerEntryPoint`
<p>

**타입:** `{ path: string | URL, namedExports: string[] }`<br />
**기본값:** `{ path: '@astrojs/cloudflare/entrypoints/server.js', namedExports: [] }`<br />
<Since v="12.6.0" pkg="@astrojs/cloudflare"/>
</p>

`astro build` 명령을 사용할 때, Cloudflare Worker의 [workerEntryPoint](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/rpc/)를 지정하는 구성 객체입니다.

이 객체를 통해 사용자 정의 파일 경로 (`path`)와 `namedExports`를 모두 선택적으로 지정할 수 있습니다.

```js title="astro.config.mjs"
import cloudflare from '@astrojs/cloudflare';
import { defineConfig } from 'astro/config';

export default defineConfig({
	adapter: cloudflare({
		workerEntryPoint: {
			path: 'src/worker.ts',
			namedExports: ['MyDurableObject']
		}
	}),
});
```

#### `workerEntryPoint.path`

<p>

**타입:** `string`<br />
**기본값:** `@astrojs/cloudflare/entrypoints/server.js`
<Since v="12.6.0" pkg="@astrojs/cloudflare" />
</p>

항목 파일의 경로입니다. 이 경로는 Astro 프로젝트의 루트의 상대 경로여야 합니다.

기본적으로 어댑터는 `fetch` 핸들러만 지원하는 일반 항목 파일을 사용합니다.

다른 [Cloudflare 호출 핸들러](https://developers.cloudflare.com/workers/observability/logs/workers-logs/#invocation-logs)를 지원하기 위해 사용자 정의 파일을 생성하여 진입점으로 사용할 수 있습니다. 이는 다른 핸들러에 의존하는 기능 (예: Durable Objects, Cloudflare Queues, Scheduled Invocations)을 사용하는 경우에 유용합니다.

#### `workerEntryPoint.namedExports` 

<p>

**타입:** `[]`<br />
**기본값:** `[]`
<Since v="12.6.0" pkg="@astrojs/cloudflare" />
</p>

항목 파일에서 사용할 명명된 내보내기를 담은 배열입니다.

[사용자 정의 항목 파일](#사용자-정의-cloudflare-worker-항목-파일-만들기)의 정의된 모든 명명된 내보내기를 제공합니다. (예: `DurableObject`) 제공하지 않으면 기본 내보내기만 포함됩니다.

#### 사용자 정의 Cloudflare Worker 항목 파일 만들기

사용자 정의 항목 파일은 필요한 모든 핸들러가 포함된 `default` 내보내기를 반환하는 `createExports()` 함수를 내보내야 합니다.

다음은 Durable Object와 큐 핸들러를 등록하는 항목 파일의 예시입니다.

```ts title="src/worker.ts"
import type { SSRManifest } from 'astro';
import { App } from 'astro/app';
import { handle } from '@astrojs/cloudflare/handler'
import { DurableObject } from 'cloudflare:workers';

class MyDurableObject extends DurableObject<Env> {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env)
  }
}

export function createExports(manifest: SSRManifest) {
	const app = new App(manifest);
	return {
		default: {
			async fetch(request, env, ctx) {
				await env.MY_QUEUE.send("log");
				return handle(manifest, app, request, env, ctx);
			},
			async queue(batch, _env) {
				let messages = JSON.stringify(batch.messages);
				console.log(`큐에서 처리한 메시지: ${messages}`);
			}
		} satisfies ExportedHandler<Env>,
		MyDurableObject: MyDurableObject,
	}
}
```

## Cloudflare 런타임

### 사용법

Cloudflare 런타임을 통해 `wrangler.toml`/`wrangler.jsonc` 구성 파일에 정의된 환경 변수 및 Cloudflare 리소스에 대한 바인딩에 액세스할 수 있습니다.

`Astro.locals.runtime`을 통해 바인딩에 접근할 수 있습니다.

```astro title="src/pages/index.astro"
---
const { env } = Astro.locals.runtime;
---
```

`context.locals`를 통해 API 엔드포인트에서 런타임에 액세스할 수 있습니다.

```js title="src/pages/api/someFile.js"
export function GET(context) {
  const runtime = context.locals.runtime;

  return new Response('Some body');
}
```

Cloudflare 문서에서 [지원되는 모든 바인딩 목록](https://developers.cloudflare.com/workers/wrangler/api/#supported-bindings)을 확인하세요.


### 환경 변수 및 비밀

Cloudflare 런타임은 환경 변수를 일종의 바인딩으로 취급합니다.

예를 들어, `wrangler.jsonc`에서 다음과 같이 [환경 변수](https://developers.cloudflare.com/workers/configuration/environment-variables/#add-environment-variables-via-wrangler)를 정의할 수 있습니다.

```jsonc title="wrangler.jsonc"
{
  "vars" : {
    "MY_VARIABLE": "test"
  }
}
```

비밀은 암호화된 텍스트 값을 Worker에 연결할 수 있도록 하는 특별한 유형의 환경 변수입니다. 설정 후에는 보이지 않도록 다르게 정의해야 합니다.

`secrets`를 정의하려면 Wrangler 구성 파일이 아닌 [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/)를 통해 추가하세요.

```bash
npx wrangler secret put <KEY>
```

로컬 개발 환경에서 비밀을 설정하려면 Astro 프로젝트의 루트에 `.dev.vars` 파일도 추가해야 합니다.

```ini title=".dev.vars"
DB_PASSWORD=myPassword
```

그러면 `Astro.locals.runtime`에서 사용할 수 있는 `env` 객체를 통해 비밀을 포함한 환경 변수에 접근할 수 있습니다.

```astro title="src/pages/index.astro"
---
const { env } = Astro.locals.runtime;
const myVariable = env.MY_VARIABLE;
const secret = env.DB_PASSWORD;
---
```

Cloudflare 환경 변수와 비밀은 [`astro:env` API](/ko/guides/environment-variables/#타입-안전-환경-변수)와 호환됩니다.

### 타입 설정

`wrangler`는 바인딩을 위한 TypeScript 타입을 생성하는 `types` 명령을 제공합니다. 이를 통해 수동으로 타입을 설정하지 않고도 locals의 타입을 설정할 수 있습니다. 자세한 내용은 [Cloudflare 문서](https://developers.cloudflare.com/workers/wrangler/commands/#types)를 참조하세요.

구성 파일 (예: `wrangler.toml`, `.dev.vars`)을 변경할 때마다 `wrangler types`를 실행해야 합니다.

:::note
자동으로 다른 명령보다 먼저 `wrangler types`를 실행하는 pnpm 스크립트를 만들 수 있습니다.

```json title="package.json"
{
  "scripts": {
    "dev": "wrangler types && astro dev",
    "start": "wrangler types && astro dev",
    "build": "wrangler types && astro check && astro build",
    "preview": "wrangler types && astro preview",
    "astro": "astro"
  }
}
```
:::

`Runtime`을 사용한 [전역 타입 확장](/ko/guides/typescript/#전역-타입-확장하기)을 통해 `runtime` 객체의 타입을 지정할 수 있습니다.

```ts title="src/env.d.ts"
type Runtime = import('@astrojs/cloudflare').Runtime<Env>;

declare namespace App {
  interface Locals extends Runtime {
    otherLocals: {
      test: string;
    };
  }
}
```

## Cloudflare 플랫폼

### Headers

Astro 프로젝트의 `public/` 폴더에 `_headers` 파일을 추가하여 [사용자 정의 헤더](https://developers.cloudflare.com/pages/platform/headers/)를 응답에 첨부할 수 있습니다. 이 파일은 빌드 출력 디렉터리에 복사됩니다.

이 기능은 Cloudflare Workers와 Pages에서 사용할 수 있습니다.

### Assets
Astro가 빌드한 자산은 모두 해시로 이름이 지정되므로 긴 캐시 헤더가 제공될 수 있습니다. 기본적으로 Cloudflare의 Astro는 이러한 파일에 대한 헤더를 추가합니다.

### Redirects

요청을 다른 URL로 리디렉션하기 위해 [사용자 정의 리디렉션](https://developers.cloudflare.com/pages/platform/redirects/)을 선언할 수 있습니다. 이렇게 하려면 Astro 프로젝트의 `public/` 폴더에 `_redirects` 파일을 추가하세요. 이 파일은 빌드 출력 디렉터리로 복사됩니다.

이 기능은 Cloudflare Workers와 Pages에서 사용할 수 있습니다.

### Routes
#### Cloudflare Workers의 라우팅

정적 자산 라우팅은 빌드 디렉터리 (예: `./dist`)의 파일 구조를 기반으로 합니다. 일치하는 항목이 없으면 요청 시 렌더링을 수행하기 위해 Worker로 대체됩니다. [Cloudflare Workers를 사용한 정적 자산 라우팅](https://developers.cloudflare.com/workers/static-assets/routing/)에 대해 자세히 알아보세요.

[Cloudflare Pages](#cloudflare-pages의-라우팅)와 달리 Workers에서는 `_routes.json` 파일이 필요하지 않습니다.

현재 Cloudflare 어댑터는 항상 이 파일을 생성합니다. 이 문제를 해결하려면 `public/` 폴더에 `.assetsignore` 파일을 만들고 다음 줄을 추가하세요.
  ```txt title="public/.assetsignore"
  _worker.js
  _routes.json
  ```

#### Cloudflare Pages의 라우팅

Cloudflare Pages의 [라우팅](https://developers.cloudflare.com/pages/platform/functions/routing/#functions-invocation-routes)은 `_routes.json` 파일을 사용하여 어떤 요청이 서버 함수로 라우팅되고 어떤 요청이 정적 자산으로 제공되는지 결정합니다. 기본적으로 `_routes.json` 파일은 프로젝트의 파일 및 구성을 기반으로 자동으로 생성됩니다.

어댑터 구성에서 [따라야 하는 추가 라우팅 패턴을 지정](#routesextend)하거나, 사용자 정의 `_routes.json` 파일을 만들어 자동 생성을 완전히 덮어쓸 수 있습니다.

사용자 정의 `public/_routes.json`파일을 생성하면 자동 생성이 재정의됩니다. 자세한 내용은 [사용자 지정 `_routes.json` 생성에 대한 Cloudflare 문서](https://developers.cloudflare.com/pages/platform/functions/routing/#create-a-_routesjson-file)를 참조하세요.

## 세션

[Astro 세션 API](/ko/guides/sessions/)를 사용하면 요청 간에 사용자 데이터를 쉽게 저장할 수 있습니다. 이는 사용자 데이터 및 환경 설정, 쇼핑 카트, 인증 자격 증명과 같은 용도로 활용될 수 있습니다. 쿠키 저장소와는 달리 데이터 크기에 제한이 없으며, 다른 기기에서도 복원할 수 있습니다.

Cloudflare 어댑터를 사용하는 경우 Astro는 세션 스토리지를 위해 [Workers KV](https://developers.cloudflare.com/kv/)를 자동으로 구성합니다. 세션을 사용하기 전에 데이터를 저장할 KV 네임스페이스를 생성하고 Wrangler 구성 파일에 KV 바인딩을 설정해야 합니다. 기본적으로 Astro는 KV 바인딩 이름이 `SESSION`일 것으로 예상하지만, 어댑터 구성에서 [`sessionKVBindingName`](#sessionkvbindingname) 옵션을 설정하여 원하는 다른 이름을 선택할 수 있습니다.

<Steps>

1. Wrangler CLI를 사용하여 KV 네임스페이스를 생성하고 새 네임스페이스의 ID를 기록해 두세요.

   ```sh
   npx wrangler kv namespace create "SESSION"
   ```

2. Wrangler 구성에서 KV 네임스페이스를 선언하고, 네임스페이스 ID를 이전 명령에서 반환된 ID로 설정합니다.

    <Tabs>
      <TabItem label="wrangler.jsonc">
        ```json title="wrangler.jsonc" "<KV_NAMESPACE_ID>"
        {
          "kv_namespaces": [
            {
              "binding": "SESSION",
              "id": "<KV_NAMESPACE_ID>"
            }
          ]
        }
        ```
      </TabItem>
      <TabItem label="wrangler.toml">
        ```toml title="wrangler.toml" "<KV_NAMESPACE_ID>"
        kv_namespaces = [
          { binding = "SESSION", id = "<KV_NAMESPACE_ID>" }
        ]
        ```
      </TabItem>
    </Tabs>

3. 그러면 서버 코드에서 세션을 사용할 수 있습니다.

    ```astro title="src/components/CartButton.astro" "Astro.session?.get('cart')"
    ---
    export const prerender = false;
    const cart = await Astro.session?.get('cart');
    ---

    <a href="/checkout">🛒 {cart?.length ?? 0} items</a>
    ```

</Steps>

:::note
Cloudflare KV에 쓰는 작업은 리전 간에 [최종 일관성을 보장](https://developers.cloudflare.com/kv/concepts/how-kv-works/#consistency)합니다. 즉, 동일한 리전 내에서는 변경 사항이 즉시 반영되지만, 전역적으로 전파되는 데 최대 60초가 걸릴 수 있습니다. 대부분의 사용자는 요청 간에 리전을 전환할 가능성이 낮으므로 이에 영향을 받지 않겠지만, VPN 사용자 등 일부 사용 사례에서는 고려해야 할 사항일 수 있습니다.
:::

## Cloudflare 모듈 가져오기

Cloudflare `workerd` 런타임은 일부 [비표준 모듈 타입](https://developers.cloudflare.com/workers/wrangler/bundling/#including-non-javascript-modules) 가져오기를 지원합니다. 대부분의 추가 파일 타입은 Astro에서도 사용할 수 있습니다.

- `.wasm` 또는 `.wasm?module`: 인스턴스화할 수 있는 [`WebAssembly.Module`](https://developer.mozilla.org/ko/docs/WebAssembly/JavaScript_interface/Module)을 내보냅니다.
- `.bin`: 파일의 원시 바이너리 콘텐츠의 [`ArrayBuffer`](https://developer.mozilla.org/ko/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)를 내보냅니다.
- `.txt`: 파일 콘텐츠의 문자열을 내보냅니다.

모든 모듈 타입은 단일 기본값을 내보냅니다. 모듈은 서버 측에서 렌더링된 페이지 또는 정적 사이트 생성을 위해 사전 렌더링된 페이지에서 가져올 수 있습니다.

다음은 요청의 숫자 매개변수를 함께 추가하여 요청에 응답하는 Wasm 모듈을 가져오는 예시입니다.

```js title="pages/add/[a]/[b].js"
// WebAssembly 모듈 가져오기
import mod from '../util/add.wasm';

// 사용하기 위해 먼저 인스턴스화
const addModule: any = new WebAssembly.Instance(mod);

export async function GET(context) {
  const a = Number.parseInt(context.params.a);
  const b = Number.parseInt(context.params.b);
  return new Response(`${addModule.exports.add(a, b)}`);
}
```

이 예시는 사소하지만 Wasm을 사용하면 이미지 처리 라이브러리를 포함하거나 읽기 전용 데이터 세트에 대한 검색을 위해 미리 인덱싱된 작은 데이터베이스를 포함하는 등 중요한 I/O를 포함하지 않는 계산 집약적인 작업을 가속화할 수 있습니다.

## Node.js 호환성

기본적으로 Cloudflare는 Node.js 런타임 API를 지원하지 않습니다. 일부 구성에서는 Cloudflare가 Node.js 런타임 API의 하위 집합을 지원합니다. Cloudflare의 [문서](https://developers.cloudflare.com/workers/runtime-apis/nodejs)에서 지원되는 Node.js 런타임 API를 찾을 수 있습니다.

이러한 API를 사용하려면 페이지 또는 엔드포인트가 서버 측에서 렌더링되어야 하며 (사전 렌더링되지 않음) `import {} from 'node:*'` 가져오기 구문을 사용해야 합니다.

```js title="pages/api/endpoint.js"
export const prerender = false;
import { Buffer } from 'node:buffer';
```

또한 `node:*` import 구문을 허용하려면 Astro 구성에서 `vite` 구성을 수정해야 합니다.

```js title="astro.config.mjs" ins={6-10}
import { defineConfig } from "astro/config";
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  adapter: cloudflare({}),
  vite: {
		ssr: {
			external: ['node:buffer'],
		},
	},
})
```

또한 활성화를 지원하는 방법에 대한 Cloudflare 문서를 따라야 합니다. 자세한 지침은 [Node.js 호환성 활성화에 대한 Cloudflare 문서](https://developers.cloudflare.com/workers/runtime-apis/nodejs/)를 참조하세요.

:::note[패키지 호환성에 미치는 영향]
프로젝트가 Node.js 런타임 API를 사용하는 서버로 패키지를 가져오는 경우, Cloudflare에 배포할 때 문제가 발생할 수 있습니다. 이 문제는 `node:*` import 구문을 사용하지 않는 패키지에서 발생합니다. 패키지가 위 import 구문을 지원하는지 확인하기 위해 패키지 작성자에게 문의하는 것이 좋습니다. 패키지가 이를 지원하지 않으면 다른 패키지를 사용해야 할 수도 있습니다.
:::

## Wrangler로 미리보기

[`wrangler`](https://developers.cloudflare.com/workers/wrangler/)를 사용하여 애플리케이션을 로컬에서 실행하려면 미리보기 스크립트를 업데이트하세요.

Workers를 사용하는 경우:

```json title="package.json"
"preview": "wrangler dev"
```

Pages를 사용하는 경우:

```json title="package.json"
"preview": "wrangler pages dev ./dist"
```

[`wrangler`](https://developers.cloudflare.com/workers/wrangler/)를 사용하여 개발하면 [Cloudflare 바인딩](https://developers.cloudflare.com/pages/platform/functions/bindings), [환경 변수](https://developers.cloudflare.com/pages/platform/functions/bindings/#environment-variables), [cf 객체](https://developers.cloudflare.com/workers/runtime-apis/request/#incomingrequestcfproperties)에 액세스할 수 있습니다. Wrangler와 함께 작동하도록 핫 리로드 또는 Astro 개발 서버를 사용하려면 사용자 정의 설정이 필요할 수 있습니다. [커뮤니티 예시](https://github.com/withastro/roadmap/discussions/590)를 참조하세요.

### 의미 있는 오류 메시지

현재 Wrangler에서 애플리케이션을 실행하는 동안 발생하는 오류는 코드 축소로 인해 그다지 유용하지 않습니다. 더 나은 디버깅을 위해 `astro.config.mjs` 파일에 `vite.build.minify = false` 설정을 추가할 수 있습니다.

```js title="astro.config.mjs" ins={3-7}
export default defineConfig({
  adapter: cloudflare(),
  vite: {
    build: {
      minify: false,
    },
  },
});
```

[astro-integration]: /ko/guides/integrations-guide/
